home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Workbench Add-On
/
Workbench Add-On - Volume 1.iso
/
DiskUtil
/
Misc
/
BTNTape
/
doc
/
features.doc
< prev
next >
Wrap
Text File
|
1994-04-03
|
11KB
|
245 lines
This section of the BTN documentation discusses the features of BTN
that are useful, interesting, or different from most tape software.
**** BTNtape: an AmigaDOS handler for SCSI tape drives
**** Version 3.0 3/14/94
**** Freeware by Bob Rethemeyer (drBob@cup.portal.com)
**** (c) Copyright 1990, 1994 Robert Rethemeyer.
CONTENTS:
The Monitor program
End-of-tape handling
Error handling
Read-only mode
Append-only mode
File number tracking
Raw command interface
User-specified mode select
BUGS (anomalous features)
THE MONITOR PROGRAM
Included in with the handler is the TAPEMON program. TAPEMON is
a program that runs under a separate CLI and prints one-liner
messages from the handler. The messages include the current
tape operation and block number, and error and sense codes.
The handler will run with or without TAPEMON; i.e. TAPEMON is optional.
TAPEMON may be started either before or after the handler is mounted.
Read tapemon.doc for more information.
END-OF-TAPE HANDLING
NOTE: I cannot fully guarantee BTN's handling of end-of-tape conditions,
because I was unable to test it. If you want to risk it anyway,
keep these things in mind:
If the application reaches the end of the tape, the handler will put up
a requester asking you to insert the next tape and click "Continue",
or click "Abort". The continue option allows the application program
to access a file across multiple tape volumes without interruption.
WAIT FOR TAPE MOTION TO STOP on the new tape before clicking Continue.
If you click Abort, end-of-file is returned to the application,
and any unused data in the buffers is discarded.
*IMPORTANT NOTES*
* EOT handling may not work correctly on all drives. Test it before
trusting your data to it. Read the archive back using the -t option
of TAR. If TAR hiccups on a file after the tape swap, it doesn't work.
You can backup partitions or directories smaller than the tape capacity
to avoid this situation.
* EOT handling for direct access drives will work only if the drive
supports the READ_CAPACITY SCSI command. If you see no "Capacity"
message from TAPEMON, then EOT handling is unavailable.
ERROR HANDLING
This tape handler deals with tape errors in only a rudimentary way.
If the tape drive cannot deal with a medium or device error, it
reports it to BTN as bad status. BTN, in turn, can pass bad status
to your application program, depending on the ER flag (see install.doc)
and a requester choice. If the ER flag is 0, your application
receives status -1 for Read() or Write(). If the ER flag is 1,
you will be shown a requester giving you a choice of how you want
to deal with the error: IGNORE or FAIL. If you click IGNORE,
BTN returns good status to your application even though the data
associated with the error may be lost or corrupted. This allows
the application to continue processing the remaining data.
Clicking FAIL will return -1 as described above.
READ-ONLY MODE
If you want to reduce the possibility that someone can write on
a tape with valuable data on it, even if the cartridge is not
write-protected, you can force BTN to operate in read-only mode.
Do this by setting the RO startup flag to 1 (see install.doc).
When operating in this mode, BTN will return error status whenever
an attempt is made to open the file for writing. However, it
does not protect the tape from damage by raw commands.
APPEND-ONLY MODE
If you have tapes with existing files, and you usually wish to just
append new files onto them, you can reduce the risk of accidentally
destroying the existing files by operating BTN in "append-only" mode.
Use the AO flag in the startup string (see install.doc).
When operating in this mode, BTN rejects attempts to open the tape
for writing unless:
a) the access name is TAPE:APP or TAPE:END
b) the access name is TAPE:NR and the tape is already
positioned after the last-written file
FILE NUMBER TRACKING
You can place multiple files on a tape, with each file separated
by a filemark. If you have many files on a tape, keeping track
of them becomes unwieldy. BTN provides a way for user programs
to ask it for the file number of the file at the current position.
For example, you could write an ARexx script to update a "directory"
file on the hard disk which lists the date and file number of
each archive on the tape. Later you can use the number to
read the file using the TAPE:n access mode (n=file number).
The file number is a value maintained by BTN; it is not obtained
from the tape drive. BTN basically just counts filemarks.
When the tape is inserted or rewound, the number is reset to zero.
For reading and writing, the number gets incremented when the
file is closed. If you append a file on the tape, BTN will count
each file until it reaches the append location.
However, to append a file and keep the file number accurate, you
must not use TAPE:APP. Instead you must use "TAPE:END", which
performs the same function as TAPE:APP, but counts each file until
it reaches the end. Unfortunately, TAPE:END is slower than TAPE:APP.
Also note, using some raw commands may fool the counter.
The file number is displayed in the TAPEMON "Opened" and "Closed"
messages, or may be obtained from the handler by a program.
To obtain the current file number, open, read, and close TAPE:POS .
(You can do this manually using the CLI command "TYPE TAPE:POS".)
This pseudo file does not access the tape, it just returns a
short string containing the file number in decimal. 0 is the
first file on the tape, 1 is the second, etc. If BTN isn't sure
of the number, it returns -1. Rewinding the tape will reset it.
You should read the number BEFORE opening the associated file,
or subtract 1 from the number obtained AFTER closing the file.
You cannot read the number while the tape is active; it must be idle.
If you are using a direct access (3M) drive, the file number returned
is actually the block number (direct access drives don't have filemarks).
Also read and save the block number AFTER writing a file to know where
to write the next file.
RAW COMMAND INTERFACE
This handler provides a means to send your own SCSI control commands
to the tape drive, without the need for a special program.
Some control commands you might want to send it would be REWIND,
UNLOAD, ERASE, FORMAT, LOCK, etc. Only control commands may be sent-
there is no provision for any data transfer; don't try it.
(As you might guess, raw commands can be dangerous.)
The raw command mode is invoked by writing data to the file name
"TAPE:RAWCMD". This magic word is how the handler knows you
want to do a raw command.
You send a command via RAWCMD using the CLI "ECHO" command:
ECHO >TAPE:RAWCMD "hex command bytes..."
You can put the ECHO command in a script or make a shell alias with it.
The exact value of the data bytes is determined by the byte format of
the SCSI command you want to send. (Refer to your drive documentation.)
The data must contain only hex digits and spaces, terminated by a newline.
Each byte of the raw command should be specified as a pair of hex
digits; separate bytes by spaces. Up to 12 bytes may be specified.
Trailing omitted bytes are assumed to be zeroes.
Command examples:
Rewind: "01"
Erase: "19" (sequential drives only)
Retension: "1B 00 00 00 03"
I have included in the distribution a small ARexx script named
TAPE.REXX . It will issue some of the common control commands
for you. Refer to the script for more information.
USER-SPECIFIED MODE SELECT
In recognition of the fact that it will never be able to provide
switches for all possible modes of all tape drives, BTNtape
allows you to set the modes of the drive directly.
These modes might include: buffering, speed, auto-loading,
disconnect/reconnect, medium type, etc.
*NOTE* Do not use this feature unless you know what you are doing.
This feature is provided for the convenience of "power users".
Most drives can get by with defaults if you do not set the modes,
so it is unlikely that not setting a mode will cause problems.
Drive modes are set using the SCSI command MODE_SELECT (0x15).
BTNtape will send its own MODE_SELECT to the drive if necessary
to set the drive to fixed block mode and set the block length.
But you may also send this command to the drive at other times,
using any data you wish.
The command is sent in a manner very similar to the RAWCMD
method described above, but the magic word MODESEL is
used instead. The handler provides the SCSI command,
and you provide the data. The data is specified in an ECHO
command as pairs of hex digits separated by spaces:
ECHO >TAPE:MODESEL "hex data bytes..."
Since each drive has different things that are affected by MODE_SELECT,
you MUST refer to the programming documentation for your drive.
But in general, the mode select data consists of a parameter
list, a block descriptor, and vendor unique parameters.
*NOTE* If you specify a block descriptor, it will behoove you to
specify the same block length as found in the mountlist entry
when using fixed block mode, or zero if using variable block mode.
The handler counts the number of bytes you enter (up to 64),
and uses that for the SCSI command data length. The drive may
be fussy about the length, so enter exactly the number of bytes
as described in your docs.
Mode Select data example:
--parmlist- ----block-descriptor--- vendorparms
00 10 00 08 03 00 00 00 00 00 04 00 11 22 33 44
| | | || ||
Buff_mode BD_Len Density Blk_Len
BUGS
Avoid using the INFO command from another CLI while a tape operation
is in progress. It may cause BTN to crash the machine. This may
also happen with any program that causes a packet to be sent to BTN.
The variable block mode of operation (VB-1) is not allowed in this
version; it has never really worked right.
Writing tapes across more than one tape cartridge is not recommended on
sequential drives. Try not to hit the end of the tape. Although BTN
is designed to handle this situation, I have not been able to test it.
If you use the old Xoper or ARTM utilities, and display the device list,
the entry for TAPE: will show garbage, and/or the Amiga may crash.
I believe this to be a bug in those programs, but this will be little
consolation to you after your machine crashes.
The TAPE: device cannot be gotten rid of without rebooting.